Manual/Automatic downloading
OpenArena includes automatic download features (a.k.a "autodownload" or "d/l" for short). When you try to connect to a server that has got some additional files (usually mods and maps) that are being used, but you do not have them on your local machine, you will not be able to connect to it. Things you can do -unless moving to another server- are to enable automatic downloading or to manually search and install the needed files (e.g. if you know that a server is using the "DeFRag" mod, you will search the web -maybe with a little help from our lists- for its download packages). Manually downloading and installing a package may have the advantage to get additional stuff, like documentation and pre-set configuration files (while automatic download works with .pk3 files ''onlyFor this reason, who creates a mod or a map should include a copy of its documentation also ''inside the pk3.), but sometimes this may not be enough because the server admin may have placed more extra stuff files that were not included with the original mod. Automatic download can provide you game patches, but cannot update your program executables files (e.g. OpenArena.exe), that have to be manually downloaded from official OpenArena web site or forum. Some tips about automatic downloads There are two kinds of automatic downloading: the "standard" one ("classic", "old style", "slow" download, suitable for very small downloads only) and the "fast" one (also known as "curl download", "www download", "http download", "ftp download" or "http redirection", very advisable but it needs a bit more effort for server setup). If you are a server admin, it is very advisable you learn to setup fast downloading. Note: when you install OpenArena, automatic downloading is disabled by default, to allow people to decide if they want or not to download extra stuff. Hint: you can try to search for documentation (and license information) also inside the .pk3 files, sometimes authors or server admins could have placed something there! A .pk3 file is just a .zip (compressed) file with a different extension, thus you should be able to read them with many programs, for example 7-Zip, free. Please be careful to do not modify files contained in .pk3 files (do not modify stock pk3 files), or then you may have problems to connect to pure servers. Tip: server admins should be sure they do not place on their servers files that may create problems to users (especially in baseoa folder). Anyway, after autodownloading something, you may potentially discover some strange behavior in the game, especially when playing locally: in that case, you may try to move elsewhere (or changing their extension) latest autodownloaded files -to disable them-, and test again. See also: FAQ#Yesterday everything worked correctly, but today I experience strange problems, Manual/Using mods#Notes for Server Administrators. Tip: they do exist some "serverside mods" which do not need the client to download stuff. Automatic download location Automatically autodownloaded files will be stored in your "homepath" folder (where your personal configuration files are stored, too. Note: "homepath" is not the name of the folder; please read homepath to get more info), thus they will be usually available for your user account only (and not for other users of the machine). But you can manually (from the operating system, after closing the game) move those pk3 files from your user's "homepath" folder to the game installation folder (where people usually places manually downloaded stuff), to allow all users of the machine to use them without the need to download more copies of the same files (the game searches for files under both installation and homepath folders). Note: it is possible to select a different homepath folder when launching the program. The game creates a subfolder for each mod used. For more info, you can take a look to: * FAQ#Configuration files and automatic downloaded files path * FAQ#Where are autodownloaded files saved? * FAQ#Can I change the directory to where configuration and autodownloaded files are saved? How to setup In short Client-side: * \cl_allowdownload 1 // Allows the client to automatically download required pk3 files. Also available from game options menu. Server-side: * \sv_allowDownload "1" // Enables the automatic download system. Allows the server to send pk3 files to the clients. * \sv_dlURL "http://www.url-to-your-files.com/path" // Sets the location of the pk3 files on the web/ftp server. Enables fast downloading. * Note that if you use PHP or another server-side language on your webserver to serve the autodownload files, you need to send a 'Content-Length' header. Otherwise the OpenArena client will crash! (Bug found in OA 0.8.5, see here) This may be enough (and if you are only a player and not a server admin, the client-side variable is the only one you need), but if you need more explanations, no problem! Just continue reading the following sections! Before we start, however, remember this: * Variables sv_allowdownload and cl_allowdownload are related to each mod configuration! So, you may have cl_allowdownload enabled in baseoa or in another mod, but while connecting to a server running a different mod, you may have cl_allowdownload disabled in that specific one, so you may not be able to download! In that case, check again cl_allowdownload is enabled, and then /reconnect to the server! * Variable sv_allowdownload tends to automatically return to 0 when closing the game. Check it is enabled, after you start your server. * "ERROR: Client/Server mismatch" error may be a cryptic way to say that either the server or the client have autodownload disabled! Standard downloading Client: simply set \cl_allowDownload 1 (default value is 0: you have to change it to 1 to be able to automatically download stuff!). You can also control this option from the Automatic downloading entry in the Setup --> Game options menu. After set it once, you should be ok. Be careful if you have tried to run some mods before turning automatic downloading on in the base game: those mods' configuration files may still have it turned off; in this case, you can try lo launch the mod and then enable the option again, or manually modify (or delete) the q3config.cfg file in the folder of that mod. Server: simply set \sv_allowDownload 1 (default value is 0: you have to change it to 1 to allow people to automatically download from your server). Enabling this is very important if you added extra stuff (like extra maps) to your server, or clients may not be able to connect until they get those files elsewhere. The new value of the variable may not be automatically stored after you close the program: using "seta sv_allowdownload 1" should be enough to have it stored; in the remote case you still have problems, an option is to create a custom configuration file for your server (and execute it when you start your server) and place the command there... another one is to add +set sv_allowdownload 1 to your OS command line which starts the OA server process. Clients will automatically download files only if both them and the server have their respective options active. Note: remember that there is a folder for each mod, and that usually all additional maps (and maybe models) are placed in the "baseoa" directory, to make them available to be used under all mods, instead of for that specific mod only (special very mod-specific maps which would not be playable at all in baseoa are an exception to this general habit). Also, consider that ALL pk3 in a mods folder (different than baseoa) are automatically downloaded also if not really required to play the current map. This means that a client may have to autodownload all custom maps contained in server's current mod folder, before being able to play the current one, even if the current one is just a stock baseoa map! Maps in baseoa, instead, are only downloaded if their pk3 file is really needed at the moment. A few mods (e.g. CPMA) may implement checks to force ALL of their maps to be downloaded before being able to play, even if they are in baseoa folder and are not actually used; however they should be very few mods. Seeing this from a different perspective, if you want the clients to autodownload stuff such additional player models/skins and texture packs, you should place them in a mod folder, so the clients will download everything before joining the server (while in baseoa, they would download only the pk3 containing the .bsp (map) file currently in use). DO NOT place gameplay-modifying files (e.g. custom VMs) in baseoa folder, or players will find their base game modified when playing offline! DO NOT FORGET THIS! Extremely important: "standard download" (a.k.a. "classic download", "old style download", "slow download"...) works only at the maximum speed allowed by "\rate" (client-side) and "\sv_maxrate" (server-side) variables values, and the maximum reachable speed is about 25000 bytes per secondAfter setting sv_maxrate, setting an higher sv_fps value may have the side effect to actually push your server to use more upload bandwidth than the standard 25KBps cap, but not as high as using "fast download" mode, and may also have strange effects on the game (sv_fps influences the speed at which the server simulates the in-game world). Changing sv_fps is not advisable, unless you know exactly what you are doing!. This comes from Quake 3 (the original game at the base of the source code of OpenArena). This means that, even if you have a 20 Mbit line, your download will not go over about 20-25 KByte/s (that means about 140-175 seconds to download a 3,5 MB map). Unacceptable for large downloads (even if the original Quake 3 game allows only this method). Unless your server has got only very small extra files, if you are a server admin you really should setup fast downloading. As a last note, in recent ioquake3 revisions, a new cvar called /sv_dlRate allows to uncap the contents uploading speed without the need to use an external webhost. It's a sort of mid-way between "slow" and "fast" download modes. As far as OpenArena 0.8.8, this is not yet available in official OA executables. You can try the experimental binaries to use this new functionality. Remember that players downloading will be allowed to consume more of your server bandwidth (depending from sv_dlRate) than users actually playing (depending from sv_maxRate), and this may be a problem. For general infos about OA bandwidth requirements/calculation, see Servers#Bandwidth. Fast downloading Note: if you are simply a player and not a server admin, and from your machine you can surf the web freely, you do not have to set anything more than turning on automatic downloading option, like with the classic mode, thus you can skip this part. After having set up the standard download, you can set an additional option to allow high download speeds for clients that join your server. We are talking about what may be referred "www download", "http redirection", "http download" or simply "fast downloading" or "fast d/l". This is achieved by connecting to a web server or ftp server using HTTP or FTP protocol (that work with TCP, while the standard download uses UDP protocol -directly from the game server- instead). Fast downloading comes from ioquake3 (a modified version of the open source id Tech 3 engine, that added many fixes and features to Quake 3; ioq3 is the engine that OpenArena uses). Probably HTTPS and FTPS aren't currently supported. First, place a copy of the needed pk3 files into a web server or ftp server (please be sure to place the same version of the pk3 files in both game and file servers). The clients will need to access that server to use fast downloading, so be sure it is correctly configured and accessible. This means the clients will need their firewalls permit outgoing HTTP (default TCP port 80) or FTP (default TCP port 21) -and usually this is not a problem-, while the routers and firewalls used by the server have to allow and forward incoming traffic for the right port to the server machine. We will not tell you here how to setup a web server (there are various web server softwares: maybe you may start from reading the Internet Information Services, Apache HTTP Server, Comparison of web server software, List of FTP server software pages on Wikipedia). A good solution may be using a third party web server: there are providers that offer web space at no charge (or, if you need additional space or bandwidth, at reasonable price)... this way, you would not have to worry about the web server configuration, and you would preserve the precious bandwith of your game server. In case your OpenArena fast d/l repository (web or ftp server) uses the same internet connection as your OpenArena game server, you may take a look to your web/ftp server configuration, to see if it is possible to place a maximum bandwidth usage limit: you may use that limit to prevent http/ftp traffic to cause already-connected players to lag while playing; or you may try to use QoS features on your router/firewall to give a lower priority to http or ftp data. Note: you may even use "Dynamic DNS" services (some examples: 1, 2) to make your server accessible using a static address even if in reality it is using a dynamic IP. In short, re-create the "baseoa" directory (and, if needed, your mod folder) from your game server into a web server, placing the same pk3 files in the same folders on both servers. Then use the "\sv_dlURL " variable to inform OpenArena about the path where you placed the needed files online. E.g.: \sv_dlURL "http://www.yourwebhost.com" or \sv_dlURL "http://www.yourwebhost.com/OpenArena", or sv_dlURL "ftp://ftp.yourserver.com/folder (you do not have to type a "/" at the end of the address, like http:/your-server.com/OpenArena/, because the final "/" is automatically added by the engine). Example: if the clients have to download a file called "test.pk3" in "baseoa" folder, if you set \sv_dlURL "http://www.yourwebhost.com", you have to make that file available from your web server at the following path, "http://www.yourwebhost.com/baseoa/test.pk3". Sv_dlURL is a server-side variable: players do not need to set it on their clients. When a client will need to download a pk3, the game server will redirect it to the web server: the final user will see his download much faster (it is not limited by "\rate" or "\sv_maxrate" variables: actual speed depends from the server and the client connections, anyway downloads at 500 KB/sec are quite common, this means 7 seconds to download a 3,5 MB map). After downloading from the HTTP or FTP server (using TCP protocol), the client will enter the match on the game server (via UDP protocol). If the client will not be able to locate the needed files on the specified web server, it will download them from the game server, using the slow mode. To disable fast downloading from your server, simply make the sv_dlurl variable empty (\sv_dlurl ""). It is sure that fast downloading works with "anonymous" FTP (for some info, see on Wikipedia), but it is quite probable it may work also with password-protected FTP: probably the "username:password@host" URL notation (see here) may work. Example: \sv_dlURL "ftp://username:password@ftp.yourserver.com/folder". Few words about security: FTP protocol is not "secure" (it does not encrypt anything, included the password, thus it is possible it may be "sniffed"), but usually (e.g. when you use an FTP client, like FileZilla) an hacker/cracker has to purposely intercept its packets to get your password. Including the password in the URL, instead, probably means that it will be clearly logged (stored) in proxy server logs, router logs, ISP logs, theoretically allowing many people to know it, even if they were not searching for it. Don't panic! Simply, it is advisable to create a read-only user into the ftp server (different from your usual usernames/passwords you use, both there and elsewhere), and be sure it does not have access to confidential files. IMPORTANT: About security, if you setup an HTTP or FTP server (fast download): please check that only the pk3 files will be available for public downloading from that server (remember that it would be possible to download files from it also from outside OpenArena, simply using a web browser!)... unless needed for some reason, it is advisable to do not place your configuration files there... and if you have to place them there (e.g. in case you would use the same machine for the game server and the web server, and you would not want to duplicate all your files), double check file permissions to be sure that at least those that contain your passwords (containing "rconpassword" -for remote control-, "g_password" -for private server-, "sv_privatePassword" -for reserved slots- variables) and the admin.dat file (if you use them) are not downloadable via http or ftp by everyone. All files with .cfg or .dat extensions, for example, should not be available for http/ftp internet guests... and probably .log files, too... so letting only .pk3 files publicly available is advisable. Please, do not leech: remember that it's not polite to use someone else's bandwidth without his approval. This means that you should make sv_dlURL point to web space paid or set up or registered by your own. If the web server is paid by someone else, you should ask for his approval before (he may grant it). Please do not make your users download stuff from third-party OpenArena web servers without permission: bandwidth theft is not a nice thing! Please remember that it is possible to host your files using free web hosting services (few examples: 1, 2, 3). Note: free web host services may want you to actually create a web site on those spaces... so you may rely on a web storage service instead. Please notice that the web storage service has to let unregistered people to download the files directly, pointing to their real names instead of using encrypted file names, and without having to pass through "click-here-to-download" web pages. E.g.: if you can use your web browser to download a "baseoa/pak0.pk3" file directly from a link like http://www.website.com/user/baseoa/pak0.pk3 it should be okay... if you are forced to use a link like http://www.website.com/user/kladhncgaUPSnSi6457789mnsa3 to reach that file, it is a problem. Again: if you can't/don't want to create your own http server from scratch, you can simply register to free third-party services, instead of stealing bandwidth from someone else who is paying for it. On the other side, server admins who do not want to allow third-party OA servers to "leech" bandwidth from their HTTP servers, may be able to restrict file access depending from HTTP_REFERER, that ioquake3 sets as "ioQ3://{SERVER_IP}:{SERVER_PORT}". For example, Apache's mod_rewrite can restrict access based on HTTP_REFERER. This means that you may set your web server to accept only requests coming from users that are trying to connect to your OpenArena game server, and reject requests from users that are trying to connect to other game servers. Troubleshooting tip: in case clients encounter 404 error (file not found) while trying to autodownload some speicifc files from your http server, a possible reason may be due to "case sensitive" problems, so if you had "mymap.PK3" try renaming it to "mymap.pk3" (depending from the OS you are using, you may need to pass through a temporary name such as "mymap.temp" first, in order to do a case-only renaming) on the server, then try again downloading it from a client. cURL library troubleshooting If on your client you experience you are not able to autodownload at high speed from any server, you may find an error similar to "Loading "libcurl.so.3"...WARNING: could not load cURL library" in OA console. It may happen, for example, if you copied an OA configuration from an operating system to another (e.g. from Linux to MacOS, or from a Linux distribution to another.). In that case, you may try to delete the "cl_cURLLib" entry from your q3config.cfg file and lauching the game again, or manually restore it to its default (you can read its default value by typing /cl_curllib '' in console, or just enter ''/reset cl_curllib to directly restore to its default value). In case you have another version of the required library in your system (in Linux console, you can try "locate" command to find it), e.g. libcurl.so.4 or libcurl.so.3, or simply libcurl.so, you can try to manually change the variable value to meet your file name. As a last resort, you may even try to use your Linux file system to link a library name to the other (e.g. if the program looks for "libcurl.so.3", in your Linux console you can try "locate libcurl.so" (so you find the location of libcurl.so), then type a command like ln -s /usr/lib/libcurl.so /usr/lib/libcurl.so.3 to make libcurl.so.3 as a link to libcurl.so -note that in your case you may have "/usr/lib64" instead of "/usr/lib"-). Note: some versions of binaries may have the required library built-in in themselves, and may consequently ignore the value contained in the variable; this is more probable with Windows executables (in this case, you should not experience any problem, and you should get not libcurl-related errors). Fast, slow or both As told, the standard behavior (if the game server allows downloading and sets a sv_dlURL address) is that the clients search the needed files on the web server (fast download), and if they do not find them, they get them from the game server (slow download). But, according with the ioquake3 README, it is even possible to set a different behavior. * \sv_allowDownload can be set to: ** 0: do not allow clients to autodownload stuff. Players will need to get required extra files (if any) in other ways, before being able to join your server. Default value. ** 1: allow clients to autodownload stuff from both fast and slow modes. Revert to slow mode if file not found on the web server for fast mode. Advisable value. Note: fast mode needs sv_dlURL set to point to a pre-prepared web server. ** 4: do not allow UDP download. Clients can use fast download mode only; if they cannot get the file from the web server, they will not be able to play. Note: fast mode needs sv_dlURL set to point to a pre-prepared web server. ** 8: do not ask the client to disconnect when using HTTP/FTP. Usually a client is disconnected from the game server when it starts a fast download, and re-joins it after finishing downloading (that means that someone can "steal" his "slot" while it's downloading, with the risk -relatively low, since fast downloads usually last few seconds- to find the server full, with all slots busy), and if you set it to 8, instead, it continues to maintain his slot "busy" and no one can "steal" it. * \cl_allowDownload can be set to: ** 0: this client will not autodownload stuff. If a server requires extra files (not included with the default OpenArena installation), you will need to get them manually elsewhere before being able to join that server. In some cases, extra files of the server may not be strictly necessary (e.g. player skins), so you may connect to it anyway. Default value. ** 1: this client will autodownload stuff as needed, in fast or slow mode depending from the server. Advisable value. ** 2: do not use HTTP/FTP downloads. This client will use old-style slow download only. If slow mode is disabled on the server, it will not be able to get the needed extra files. ** 4: do not use UDP downloads. This client will use www fast download only. If fast mode is disabled on the server (or the needed file is missing on the web server), the client will not be able to get the needed extra files. Licensing Stuff that you get using autodownload is probably not from the OpenArena team, but often from third-party authors, and may come with licenses different from the GPLv2 (the license that covers everything that comes "out of the box" when you first install the game, but may not cover additional stuff later added). It is common that the authors of additional stuff allow to download, use and maybe also redistribute it at no charge, but without releasing it under a free license (without the right for you to modify it, or to get money from it); we invite authors to make their additional stuff available under the GPLv2, but it's their choice (anyway, only GPLv2 stuff will be placed in any future official release of OpenArena). Search for licensing info inside pk3 files (you can open pk3s with programs that manage .zip compressed files).. Notes See also * Servers * Manual/Multiplayer * Configuration examples * Command console * Tweak * Manual/Using mods * A couple of forum threads about fast downloading: 1, 2 Category:Manual Category:Configuration examples Category:Servers